package com.qdhh.enrollment.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.Components;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * Knife4j API 文档配置
 */
@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("校园新生入学系统 API 文档")
                .description("校园新生入学系统后端 API 接口文档\n\n" +
                    "## 认证说明\n" +
                    "- 大部分接口需要登录认证\n" +
                    "- **获取Token**：\n" +
                    "  - 小程序端：调用 `/api/miniapp/user/login` 获取token\n" +
                    "  - 管理端：调用 `/api/admin/auth/login` 获取token\n" +
                    "- **使用Token**：点击右上角「Authorize」按钮，在输入框中只输入token值（不含Bearer前缀和空格）\n" +
                    "- 登录接口不需要认证\n" +
                    "- 部分接口需要身份认证（identityVerified=1），如考试相关接口\n\n" +
                    "## 接口分组\n" +
                    "### 小程序接口（`/api/miniapp/**`）\n" +
                    "- **用户认证**：`/api/miniapp/user` - 登录、注册、更新个人信息\n" +
                    "- **档案管理**：`/api/miniapp/profile` - 查询和更新学生档案\n" +
                    "- **考试模块**：`/api/miniapp/quiz` - 获取试卷、提交答案、查询成绩\n" +
                    "- **时间轴**：`/api/miniapp/milestones` - 入学时间轴\n" +
                    "- **指南**：`/api/miniapp/guides` - 入学指南\n" +
                    "- **常见问题**：`/api/miniapp/faqs` - FAQ查询\n\n" +
                    "### 管理端接口（`/api/admin/**`）\n" +
                    "- **认证**：`/api/admin/auth` - 管理员登录、登出\n" +
                    "- **用户管理**：`/api/admin/users` - 用户列表、状态管理\n" +
                    "- **题目管理**：`/api/admin/questions` - 题目CRUD操作\n" +
                    "- **考试管理**：`/api/admin/quiz` - 题目导入、考试记录查询\n" +
                    "- **档案管理**：`/api/admin/profiles` - 学生档案审核\n" +
                    "- **记录查询**：`/api/admin/records` - 考试记录统计")
                .version("1.0.0")
                .contact(new Contact()
                    .name("开发团队")
                    .email("dev@example.com"))
                .license(new License()
                    .name("Apache 2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0.html")))
            .components(new Components()
                .addSecuritySchemes("Bearer", new SecurityScheme()
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")
                    .description("Sa-Token 认证\n\n" +
                        "**重要**：\n" +
                        "1. 先调用登录接口获取token（如：POST /api/admin/auth/login）\n" +
                        "2. 复制返回的 `data.token` 字段值\n" +
                        "3. 在下方输入框中粘贴token值（不要包含Bearer前缀和空格）\n" +
                        "4. 系统会自动添加 `Bearer` 前缀")))
            .addSecurityItem(new SecurityRequirement().addList("Bearer"));
    }
}

